##################################################################
Genesis - THUNDER FORCE III - Compression tools
##################################################################

CONTACT : oostyx (at) gmail (dot) com
About TF3 hacking : http://www.romhacking.net/docs/465/

A website dedicated to shmup rom hacking coming soon !


Thunder Force 3 has 2 compression formats : 
	- Iwanaga : DEFLATE compression (LZSS + adaptive Huffman)
	- Ohtsuka : RLE compression

These programs must be run in a command line :
	tf3dcpr.exe		Iwanaga decompressor
	tf3cpr.exe		Iwanaga compressor
	ohtsuka_dcpr.exe	Ohtsuka decompressor
	ohtsuka_cpr.exe		Ohtsuka compressor


===================================================================
Iwanaga Decompression		tf3dcpr.exe
===================================================================

Example : I want to extract hydra sprites, located at 0x20122 in
tf3.bin, which is an original Thunder Force 3 Rom file in a bin format. 
It's a sprite file so its size is 0x5000.

	tf3dcpr.exe tf3.bin 20122 5000 hydra_sprites.dat

Then hydra_sprites.dat will contain all data decompressed.


Note that these tools will display a lot of information, don't
stress, it's only some debugging information.
If you don't want to display these lines, add a redirection to a 
file, like this :

	tf3dcpr.exe 20122 5000 hydra_sprites.dat > debug.txt

All lines will be written to debug.txt instead of the console !

===================================================================
Iwanaga Recompression		tf3cpr.exe
===================================================================

Example : I edited hydra_sprites.dat, and I want now to compress 
it to inject this data in the game.

	tf3cpr.exe hydra_sprites.dat 0 5000 hydra_sprites_cpr.bin

Then hydra_sprites_cpr.bin will contain the data compressed.
You must inject this file in the rom yourself, at the good offset, and
maybe you will have to update the pointer table of level art.


===================================================================
Ohtsuka Decompression		ohtsuka_dcpr.exe
===================================================================

Example : I want to extract letters and digits, located at 0x5bb80
in tf3.bin, which is an original Thunder Force 3 rom file in a bin
format.

	ohtsuka_dcpr.exe tf3.bin 5bb80 letters.dat

Then letters.dat will contain the data decompressed.


===================================================================
Ohtsuka Recompression		ohtsuka_cpr.exe
===================================================================

Example : I edited letters.dat, and I want now to compress it to
inject this data in the game.

	ohtsuka_cpr.exe letters.dat letters.bin

Then letters.bin will contain the data compressed.
You must inject the compressed file yourself, at the good offset.


===================================================================
Iwanaga Informations
===================================================================

Uncompressed files sizes (in bytes) :
	sprites			0x5000
	planes_tiles		0x6000
	planes_maps		0x7000

To run your art in the game, sizes of uncompressed files
must be exactly the same when you'll recompress them.

To inject level art, if your compressed file is bigger than original,
you must edit the offset table dedicated to level art compressed bank,
located at 0x20000 in the game.

[0x20000] 4618 
[0x20002] 00000122 00005000 00001BBD 			(hydra)
[0x2000E] 00001CDF 00005000 00001ED2			(gorgon)
[0x2001A] 00003BB1 00005000 000020A3			(seiren)
[0x20026] 00005C54 00005000 00002222			(haides)
[0x20xxx] ..........................			(......)
	  AAAAAAAA BBBBBBBB CCCCCCCC

AAAAAAAA : offset from 0x20000 to compress bank => 0x20000 + 00000122 = 0x20122
BBBBBBBB : size of original uncompressed data	=> 00005000 = 0x5000 for sprites
CCCCCCCC : size of compressed data		=> 0x20122 + 00001BBD = 0x21cdf 
					(0x21cdf = offset of next compressed bank)


You must edit this table in the game manually, or create a tool to edit it,
because there is a lot of chances that your modified data compressed
be bigger than original.

Note : at the end of compress banks (after Orn core mappings : the last file)
there is 15079 bytes not used (0xFF bytes), you must replace these bytes
if your files are bigger, by shifting some banks. 15079 B = 14.7 KB.

Note :  Iwanaga is not only used to compress level art.


===================================================================
Ohtsuka Informations
===================================================================

The size of the uncompressed data is given at the beginning of
the compressed stream. If you want to edit the game, you will
probably have to modify some offset table, and you should read
my document (http://www.romhacking.net/docs/465/) to have
more information about data ohtsuka-compressed, locations and
offset tables.

Do not try to add bytes to the uncompressed file if you edit it
because the game is developped to load this uncompressed data
directly in VRAM, and if you add a byte, then you will corrupt
VRAM, so you will corrupt what the genesis displays.

Format of offset table is nearly the same as level art offset
table given in the section Iwanaga Informations.





